Scripting and Plugins

1. What is a plugin?
2. What is the difference between plugin types?
3. How do I use Perl scripts with Pidgin/Finch??
4. How do I compile a plugin? (UNIX-like platforms)
5. How do I compile a plugin? (Windows)
6. Why doesn't my Perl plugin show up in the Plugins dialog?
7. Where can I find documentation on writing plugins?

What is a plugin?

A plugin is an additional piece of software that, when loaded into the running Pidgin or Finch application, provides additional features and functionality. We support several types of plugins, as explained in the next question.

What is the difference between plugin types?

There are a variety of plugin types that Pidgin, Finch, and libpurple support.

• "core" (libpurple) plugin - This type of plugin is a generic plugin that has absolutely no UI code at all. It should work with any libpurple UI. Exceptions to this rule may arise if a particular UI doesn't provide implementations for certain things libpurple expects a UI to implement, such as the request API. This lack of implementation will be a problem only if the libpurple plugin requires it.
• "GTK+" (Pidgin) plugin - This type of plugin will work only with Pidgin because it depends on the GTK+ user interface Pidgin supplies. This type of plugin has the ability to use anything libpurple provides as well as anything Pidgin provides. Furthermore, a Pidgin/GTK+ plugin may provide its own custom UI for configuration or other necessary dialogs by directly implementing them in GTK+.
• "GNT" (Finch) plugin - This type of plugin will work only with Finch because it depends on the GNT user interface Finch supplies. This type of plugin has the ability to use anything libpurple provides as well as anything Finch provides. Furthermore, a Finch/GNT plugin may provide its own custom UI for configuration or other necessary dialogs by directly implementing them in GNT.
• Loader plugins (sometimes called "lopl") - These are special libpurple plugins that are invisible--they don't appear in the plugins list in a libpurple UI. These plugins enable the loading of plugins written in other languages. Our Perl plugin support is provided via a loader plugin, as is our Tcl plugin support.
• Protocol plugins (called "prpl") - These are special libpurple plugins that are invisible--they don't appear in the plugins list in a libpurple UI. They are what makes libpurple able to connect to so many networks. Each protocol plugin provides an implementation of a specific IM/chat network's protocol that libpurple can use. All protocol support in libpurple is provided via protocol plugins. As protocol plugins are libpurple plugins, they may not contain any UI code at all.

How do I use Perl scripts with Pidgin/Finch??

Save the Perl script to ~/.purple/plugins or $PREFIX/lib/purple and open the Plugins dialog. If the script is written correctly, it will appear in the list and you will be able to load it.

How do I compile a plugin? (UNIX-like platforms)

This is highly dependent on the plugin.

• Many third-party plugins provide a configure script and will compile and install via the normal routine of running the configure script, then running the make command, then running make install. Plugin authors should provide this information, if applicable to their plugin(s), on their website.
• Some plugins that ship with Pidgin, Finch, and libpurple don't compile by default. To compile these plugins, change to the appropriate directory in the source tree. The directories you have to choose from are pidgin/plugins, libpurple/plugins, and finch/plugins. Once in that directory, run the command make filename.so, where filename is the name of the plugin. For example, the Offline Messaging plugin is called offlinemsg.c, so if you wanted to build that plugin, you would run make offlinemsg.so. To install and use the plugin, you can copy the .so file to ~/.purple/plugins (creating the directory if needed) or to $PREFIX/lib/purple-2 for libpurple plugins, $PREFIX/lib/pidgin/ for Pidgin plugins, or $PREFIX/lib/finch for Finch plugins.
• Some third-party plugins rely on our build infrastructure, and will compile using the same instructions as our non-default plugins. Plugin authors should provide this information, if applicable to their plugin(s), on their site.

How do I compile a plugin? (Windows)

This section covers only building plugins included with our source distribution, as not everyone uses the same method to build a plugin on Windows. Please refer to those plugins' websites for information on building the plugins for Windows.

Read and correctly follow the instructions on BuildingWinPidgin. It is very important that you follow the instructions correctly, as a correctly configured build environment is absolutely REQUIRED for building a plugin to work.

Once the build environment is set up, build Pidgin:

~/pidgin $ make -f Makefile.mingw

Next, change to the appropriate plugins directory:

~/pidgin $ cd libpurple/plugins
### OR
~/pidgin $ cd pidgin/plugins

Once here, you can compile a specific plugin by running make -f Makefile.mingw filename.dll, where filename is the name of the plugin. For example, the Offline Messaging plugin is called offlinemsg.c, so to build this plugin you would issue the command make -f Makefile.mingw offlinemsg.dll.

Note that some third-party plugins rely on our build infrastructure and will build once you place the .c file in the appropriate plugins directory. Plugin authors should indicate this information, if applicable to their plugins, on their website.

Why doesn't my Perl plugin show up in the Plugins dialog?

If you wrote the plugin yourself, you have likely missed some important detail about implementation or need to update to the current Perl API, which has changed several times.

If you downloaded the plugin, it may be out of date due to Perl API changes. You may need to contact the author or visit the plugin's website for an update.

Where can I find documentation on writing plugins?

If you click the API link in the toolbar above, you will be taken to our doxygen-generated documentation. There is a Related Pages section in the documentation that contains a bunch of useful stuff, including a run-down of all our signals by category, a basic C plugin How-To which is slightly out of date but still a good starting point, and some useful notes on translations support for third-party plugins. There is also a How-To on writing Perl scripts, which is outdated as well. We have begun the work of migrating the C How-To to the wiki. We will be expanding it with more information.